BBS Toolkit/BBS Toolkit.iso/rbbs_pc/172anew.zip/MACROS.DOC

Text File | 1989-05-23 | 13KB | 354 lines

Documentation for Macros
by Ken Goosens 24 May 1989

Macros have been enhanced in RBBS 17.2A from being a useful
way to store multiple commands and attach a word to a string
of commands, to being one of the most powerful features in
RBBS.  They now work properly whether caller has turbo key on or off,
can have unlimited length, can be invoked anywhere, have been
integrated into questionnaires, support graphics versions,
support SmartText and Work Variables, and, most importantly, have an
entire new class of macro commands which give the sysop new
control and power.


               How Macros Are Processed

An entire macro was stacked into memory and executed.  Now,
the macro is read from file a line at a time and processed,
allowing macros to be as large as files can be, and making
macros work properly even for caller with turbo key on.

Before, macros would only be executed a command line prompt.
Now, macros can be executed from any prompt.   However, there
are a few new restrictions of macros.  1st, a macro will be
ignored if its name is the name of any command.  For example,
macro "A" would be ignored because of the A)nswer questionnaire
command.   (You must reassign "A" for a command if you want to
use it as a macro.)  2nd, the prompt for More and file directories
will not accept any macro with a single letter name.  Prompts for
text to search and replace likewise should not support macros.


                 Macros and Questionnairs

Macros can also be invoked from inside questionnaires using
the new "M" command.  Control returns to the questionnaire
when the macro is finished.  E.g. "M GETANS" inside a
questionnaire will execute the macro called GETANS.

The questionnaire command to get a response has also been
enhanced to allow the response to a questionnaire to be
stored in a specified work varible.  E.g.

            ?9 Please enter your dept

will store the answer in work variable 9.   The variable number
must occur immediately after the "?".  Work variable n can
then be referenced in macros using "[n]", e.g. "[9]".
Questionnaires can thus collect values for subsequent
macro processing.  The answer is still stored in the questionnaire
the same as before.

Questionnaire lines that display text also now support metavariable
substitution, both work variables and SmartText.

Macros have the capability to store data values in any format
desired.  So one application for of macros inside questionnaires
is to save the results in a different format.


                     Macro Commands

17.2A adds a new category of macro processing:  macro commands,
which are commands executed in the macro rather than simply
passed to RBBS as keystrokes that are typed in.   The macro
commands include:

o   display a line with no carriage return

o   display a line with carriage return

o   display a block of lines

o   display a file

o   prompt for a response and store answer

o   pause a specified # of seconds

o   stack keystrokes

o   append a block of lines to a file.

o   control whether the macro text is echoed or not

o   retrieve values from a file into a form which is the displayed

In all prompts and blocks, substitution is supported for both

o   stored answers

o   SmartText variables.


                 New Types of Applications Possible

(1)   Interactive help.  For example, you can put up a macro
      called EZDOWN to help people download.   It explains everything,
      asks for the file name and protocol, and tells the caller what they
      should be doing on their end, then drives the download.

(2)   Data Base.  Unlike questionnaires, you can totally control
      how data is written to a file.   You can put in labels, or data
      only, put the values in quotes, separate the values by commas, etc.
      Done by writing to file.   A block of text functions like a template
      into which data values are substituted.

(3)   Tours of the board can be given, to showcase new or special
      features.


                        How to Write Macros

The configuration program specified the drive/path macros are stored
on and what extension they have.  Macros are invoked using their
name as prefix.   The default drive/path is C: and the default
extension is "MCR".

All macros begin with a minimum security to use the macro, which should
be an integer on the first line.

Macro commands have the same structure as SmartText variables:

           <command prefix><command name>

where <command prefix> is the SmartText command specified in CONFIG.
The symbol "{" (ascii 123) is the default.   The <command name> consists
of two characters.   Lines that are not valid macro commands are simply
passed to RBBS as if the user had typed them in.   There are three
differences between SmartText variables and macro commands:

(1)   Macro commands must be the first three characters on a line,
      whereas SmartText variables can occur anywhere on a line.

(2)   Macro commands can have an argument after the command name, and

(3)   A macro command can apply to a block of lines following it.

The supported command names are:

*0 - display what follows on the line with no carriage return.  E.g.

            {*0Press any key to continue

*1 - display what follows on the line with a carriage return.  E.g.

         {*1{FN, I hope you enjoyed your tour of the board!

     This will substitute the first name of the caller for the
     SmartText variable "{FN".

*B - display what follows on subsequent lines, each line with a
     carriage return, up to the line beginning with "{END".  E.g.

        {*B
        Macro commands have the ability to display
        multiple lines.  The macro command is
                     {*B
        and it will display all lines until it encounters
        one beginning with {END.  Like it, {FN?
        {END

     The caller will seen everything between the first and last
     lines, with the first name substituted into the last line
     displayed.

*F - display the named file that follows.  E.g.

         {*F L:\RBBS\HELP.LST

     will display the file HELP.LST.

nn - use the text that follows on the line as a prompt and store
     the resultant answer in an internal working variable numbered nn.
     nn must be two digits and can be 01, 02, 03, ..., 30.  E.g.

         {01Please enter the Department you work for:
         {02Pease enter your Office number:

     This will store the answers in work variable # 1 and 2, which
     can be subsequently referenced as "[1]" and "[2]".

    Note:  you can have at most 30 referenced variables at a time.
    Variables can be reused but the value gets overwritten.

WT - pause for the number of seconds specified after "WT".  E.g.

            {WT 2

     will wait for 2 seconds.

>> - append the following block of text to the file specified on this
     line.  E.g.

              {>> C:MARCRO.DAT
              "{FN","{LN","[1]","[2]"
              {END

     will append the following line to the file named MACRO.DAT on
     drive C:, assuming the caller is KEN GOOSENS, and he responded
     to the above prompts for Department with "Controller" and Office #
     with "107".   Then the line what would be written out is:

              "KEN","GOOSENS","Controller","107"

     Note that as many lines can be included as desired.  Simply end
     the block to be written out with "{END" as the beginning of the
     line.

     Some data base managers want fixed length files and this
     is possible in the macro append.  Just add "/FL" on the
     macro command line.  Rather than replace, the
     substitution will overlay the line at the "[", thus keeping
     the output fixed length.  E.g. suppose 1st work variable
     has "A" as value and 2nd is "123456" and 3rd is "Henry",
     and the caller's first name is KEN.
     Then

            {>> C:\RBBS\DAT.FIL /FL
            [1][2]....[3]...............{FN........
            {END

     would add the following line into DAT.FIL

            A  123456.Henry.............KEN.........

     Normally, blanks would be put where dots are show.

ST - Stack the characters immediately following the "ST".  E.g.

                {ST

     will stack a carriage return (no characters).  And

                {STD [1] [2]

     would stack "D RBBS-EXE.ARC Z" - as if they were typed and
     Enter pressed - if the 1st work variable has
     "RBBS-PC.EXE" and the second work variable stores "Z".

     Realize that if you use macros to display text at an RBBS
     prompt like "Enter command? ", RBBS will continue to sit there
     waiting for an answer.  A stacked carriage return at the end
     will cause the prompt to be redisplayed, though the effect of
     the stack will vary with the particular prompt.

M! - Execute the named macro that follows on the same line.  E.g.

                 {M! ORDER

     will execute the macro called ORDER.  The executes are
     like "go to's" in that execution in the current macro ceases and
     does not return automatically when ORDER is done.  Note that
     the macro name is used (i.e. only the file prefix) and not
     the full file name.

ON - Case logic for macros.  Depends on value of work variable
     selected on the same line.  E.g.

             {ON 1
             =A
             M! D:\HIDDEN\CHOICEA.MCR
             =B
             {*1You have selected option B
             {02Why did you select B?
             =C
             M! D:\HIDDEN\CHOICEA.MCR
             {END ON

     Note:  the macro name can have a drive/path and/or extension.
     If only a prefix is put in, RBBS will automatically add the
     configuration drive/path and extension for macros.  But by
     putting in a different drive/path/extension from config's you
     can assure that a user cannot invoke the macro - if you want
     it to be used only internally by your application.

 EY - Echo the text passed in macros as if keystrokes.   The default
      is to echo.

 EN - Do not echo the macro keystrokes.  E.g.

        {EN
        {*1 The following commands will be executed but now shown
        {01 Press Enter when ready
        R L
        A
        {EY
        {*1 Same commands but now you will see the responses to the prompts
        {01 Press Enter when ready
        R L
        A
 << - Display fields from a file in a form.   This is one of the most
      powerful new commands in macros, which allows data to be stored in
      compact, data format but retrieved into a form for display to a
      caller.    There are 5 parameters that can follow the macro command:

           <file name>  <file format> <data#> <submode> <rec-pause>

      where "<file name>" is the name of the data file that has records
      to read, "<file format>" is "/V" if data is stored in variable
      length format and "/F" if fixed length format.  "<data#>" is the
      number of separate fields in a record for variable length data
      and the length of the data if fixed length.  "<submode>" means
      the mode by which data is substituted into the form that follows.
      Put "/FL" if the form is fixed length, meaning that data is overlaid
      into the form so as not to change any lengths.  Finally, "<rec-pause>"
      should be "/1" if you want to pause after each record rather than
      when the screen fills.

{*1 -TOPIC-    - DATA # -       - VOICE # -    -First Name-    -Last Name-
{<< C:\RBBS\RHLP.DAT /V 5 /FL
[1]         [2]              [3]             [5]             [4]
{END

Note that spaces occur after the "[4]".  If the file RHLP.DAT contains

"DOORS","404-981-7781","405-988-7782","Wizard","The"
"PROTOCOLS","709-123-4567","0","Horse","Crazy"

then the caller would see

 -TOPIC-    - DATA # -       - VOICE # -    -First Name-    -Last Name-
DOORS       404-981-7781     405-988-7782    The             Wizard
PROTOCOLS   709-123-4567     0               Crazy           Horse

The same example using fixed length data would be

{*1 -TOPIC-    - DATA # -       - VOICE # -    - Name -
{<< C:\RBBS\RFLH.DAT /F 69 /FL
[1](34:12)    [1](46:12)       [1](58:12)      [1](1:33)
{END

where RFLH.DAT contains:

The Wizard                       DOORS       404-981-7781405-988-7782
Crazy Horse                      PROTOCOLS   709-123-45670

This would produce the following for the caller:

 -TOPIC-    - DATA # -       - VOICE # -    - Name -
DOORS       404-981-7781     405-988-7782    The Wizard
PROTOCOLS   709-123-4567     0               Crazy Horse

Note that work fields support sub-field references in the format:

         [n](x:y)

where n is the work field number, x is the beginning column, and
y is the # of bytes to get.  E.g. if work field 3 has value
"123abc" then "[3](3:3)" would have "3ab" as its value.
Fixed length records are always referenced as work variable 1.

For detailed applications of macros, see RDB.DOC.